Update gateway deployment/onboarding documentation - #157
Merged
Conversation
carlosmartinez
requested review from
floormind,
mrlockstar,
saliceti and
steventux
June 30, 2026 10:56
Onboarding: add the permissions the engineer actually needs (PIM for hub and spoke, enterprise app ownership), the temporary-secret procedure and its 24-hour trap, the two subscription misconfigurations that blocked the first prod onboarding (missing Azure Connected Machine Onboarding role, unregistered resource providers), where the relay namespace is provisioned, and a proper acceptance-criteria verification step - including that a Running service which never logs "Connected - waiting" is not healthy. Promotion: the cleanup verify now has commands and a warning (pre-prod data survived the first promotion onto the prod gateway and was found a month later during a live clinic); re-onboarding creates a new managed identity so Gateway.oid must be updated or every image upload 403s; the end-to-end check goes through the Gateway actions admin; the gotchas table gains the failure modes we actually hit. Also, add live-clinic debugging runbook and diagnostic tooling. Co-authored-by: Ife Ayelabola <floormind@users.noreply.github.com>
carlosmartinez
force-pushed
the
docs/promote-preprod
branch
from
July 10, 2026 15:01
5b21fed to
30463aa
Compare
carlosmartinez
changed the title
floormind
approved these changes
Jul 14, 2026
Contributor
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Captures the operational knowledge from the first production gateway onboarding, promotion and live clinics:
onboard-hospital-vm.md— new "Who can run this" permissions section, Step 0 (temporary onboarding secret), two new troubleshooting entries for the subscription misconfigurations that blocked prod onboarding, a pointer to where the relay namespace comes from, and Step 6 rewritten as acceptance criteria (services + ports + relay log showsConnected - waiting– a Running service that never connects is the failure mode that matters; the old Log Analytics heartbeat check is unreliable while VM telemetry export is broken).promote-vm-preprod-to-prod.md— cleanup verification, theGateway.oidupdate step, end-to-end check via the Gateway actions admin, and four new gotchas from the incident.live-clinic-debugging.md(new) — symptom → check mapping for every hop of the pipeline, VM-side and Azure-side, plus the echo probe section.scripts/diagnostics/relay_echo_probe.py(new) — tests relay → gateway independently of Manage, from any laptop or from inside a Manage container.scripts/powershell/debug_toolkit.ps1(new) — VM-side query/tail/health helpers for clinic-day support.Content merged from the DevOps team's onboarding write-ups (acceptance criteria adopted nearly verbatim) plus the debug session notes. Identifiers are placeholders throughout.
Review notes — two accuracy questions for @floormind